home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / program / progem.lzh / wind7.prf < prev    next >
Text File  |  1987-06-23  |  18KB  |  406 lines
  1. .!****************************************************************************
  2. .! 
  3. .! ANTIC PUBLISHING INC., COPYRIGHT 1985.  REPRINTED BY PERMISSION.
  4. .!
  5. .! ** Professional GEM ** by Tim Oren
  6. .!
  7. .! Proff File by ST enthusiasts at
  8. .! Case Western Reserve University
  9. .! Cleveland, Ohio
  10. .! uucp : decvax!cwruecmp!bammi
  11. .! csnet: bammi@case
  12. .! arpa : bammi%case@csnet-relay
  13. .! compuserve: 71515,155
  14. .!
  15. .!****************************************************************************
  16. .!
  17. .!
  18. .!****************************************************************************
  19. .!
  20. .!            Begin Part 7
  21. .!
  22. .!****************************************************************************
  23. .!
  24. .PART VII Menu Structures
  25. .SH HAPPY NEW YEAR
  26. This is article number seven in the ST
  27. PRO GEM series, and the first for 1986.  In this installment,
  28. I will be discussing GEM menu structures and how to use them
  29. in your application.  There is  also a short Feedback
  30. response section.  You will find the download file containing
  31. the code for this column in the file GEMCL7.C in DL3 of the
  32. ATARI16 SIG (PCS-58).
  33. .SH MENU BASICS
  34. In ST GEM, the menu consists of a bar
  35. across the top of the screen which displays several sub-menu
  36. titles.  Touching one of the titles causes it to highlight,
  37. and an associated "drop-down" to be drawn  directly below on
  38. the screen.  This drop-down may be dismissed by moving  to
  39. another title, or by clicking the mouse off of the drop-down.
  40. .PP
  41. To make a selection, the mouse is moved over the
  42. drop-down.  Each  valid selection is highlighted when the
  43. mouse touches it.  Clicking the mouse  while over one of
  44. these selections picks that item.  GEM then undraws the
  45. drop-down, and sends a message to your application giving the
  46. object number  of the title bar entry, and the object number
  47. of the drop-down item which  were selected by the user.  The
  48. selected title entry is left highlighted  while your code
  49. processes the request.
  50. .SH  MENU STRUCTURES
  51. The data structure which defines a GEM
  52. menu is (surprise!) an object tree, just like the dialogs and
  53. panels which we have discussed before.  However, the
  54. operations of the GEM menu manager are quite different from
  55. those of the form manager, so the internal design of the menu
  56. tree has some curious constraints.
  57. .PP
  58. The best way to understand these constraints is to look
  59. at an  example.  The first item in the download is the object
  60. structure (only) of the menu tree from the GEM Doodle/Demo
  61. sample application.
  62. .PP
  63. The ROOT of a menu tree is sized to fit the entire
  64. screen.  To satisfy the visual hierarchy principle (see
  65. article #5), the screen is divided into two parts: THE BAR,
  66. containing the menu titles, and THE SCREEN, while contains
  67. the drop-downs when they are drawn.  Each of these areas is
  68. defined by an object of the same name, which are the only two
  69. objects linked directly below the ROOT of a menu tree.  You
  70. will notice an important implication of this structure:  The
  71. menu titles and their associated drop-downs are stored in
  72. entirely different subtrees of the menu!
  73. .PP
  74. While examining THE BAR in the example listing, you may
  75. notice that its OB_HEIGHT is very large (513).  In
  76. hexadecimal this is 0x0201.  This defines a height for THE
  77. BAR of one character plus two pixels used for spacing.  THE
  78. BAR and its subtree are the only objects which are drawn on
  79. the screen in the menu's quiescent state.
  80. .PP
  81. The only offspring object of THE BAR is THE ACTIVE.  This
  82. object defines the part of THE BAR which is covered by menu
  83. titles.  The screen rectangle belonging to THE ACTIVE is used
  84. by the GEM screen manager when it  waits for the mouse to
  85. enter an active menu title.  Notice that THE ACTIVE and its
  86. offspring also have OB_HEIGHTs with pixel residues.
  87. .PP
  88. The actual menu titles are linked left to right in order
  89. below THE ACTIVE.  Their OB_Xs and OB_WIDTHs are arranged so
  90. that they  completely cover THE ACTIVE.  Normally, the title
  91. objects are typed  G_TITLE, a special type which assures that
  92. the title bar margins are correctly drawn.
  93. .PP
  94. THE SCREEN is the parent object of the drop-down boxes
  95. themselves. They are linked left to right in an order
  96. identical with their titles, so  that the menu manager can
  97. make the correct correspondence at run-time.  The OB_X of
  98. each drop-down is set so that it is positioned below its
  99. title on the screen.
  100. .PP
  101. Notice that it is safe to overlap the drop-downs within a
  102. menu,  since only one of them will be displayed at any time.
  103. There is one constraint on the boxes however:  They must be
  104. no greater than a quarter screen in total size.  This is the
  105. size of the off-screen blit buffer which is used by GEM to
  106. store the screen contents when the drop-down is drawn.  If
  107. you exceed this size, not all the screen under the drop-down
  108. will be restored, or the ST may crash!
  109. .PP
  110. The entries within a drop-down are usually G_STRINGs,
  111. which are optimized for drawing speed.  The rectangles of
  112. these entries must  completely cover the drop-down, or the
  113. entire drop-down will be inverted  when the mouse touches an
  114. uncovered area!  Techniques for using objects  other than
  115. G_STRINGs are discussed later in this column.
  116. .PP
  117. The first title and its corresponding drop-down are
  118. special.  The title name, by custom, is set to DESK.  The
  119. drop-down must contain exactly  eight G_STRING objects.  The
  120. first (again by custom) is the INFO entry,  which usually
  121. leads to a dialog displaying author and copyright information
  122. for your application.  The next is a separator string of
  123. dashes with the DISABLED flag set.  The following six objects
  124. are dummy strings which GEM fills in with the names of desk
  125. accessories when your menu is loaded.
  126. .PP
  127. The purpose of this description of menu trees is to give
  128. you an understanding of what lies "behind the scenes" in the
  129. next section, which describes the run-time menu library
  130. calls.  In practice, the Resource Construction Set provides
  131. "blank menus" which include all of the required elements, and
  132. it also enforces the constraints on internal structure.  You
  133. only need to worry about these if you modify the menu tree
  134. "on-the-fly".
  135. .SH USING THE MENU
  136. once you have loaded the application's
  137. resource, you can ask the AES to install your menu.  You must
  138. first get the address of the menu tree within the resource
  139. using:
  140. .FB rsrc_gaddr()
  141. rsrc_gaddr(R_TREE, MENUTREE, &ad_menu);
  142. .FE
  143. assuming that MENUTREE is the name you gave the menu in the
  144. RCS, and that ad_menu is a LONG which will receive the
  145. address.  Then you call the AES to establish the menu:
  146. .FB menu_bar()
  147. menu_bar(ad_menu, TRUE);
  148. .FE
  149. At this point, the AES draws your menu bar on the screen and
  150. animates it when the user moves the mouse into the title
  151. area.
  152. .PP
  153. The AES indicates that the user has made a menu selection
  154. by sending your application a message.  The message type is
  155. MN_SELECTED,  which will be stored in msg[0], the first
  156. location in the message  returned by evnt_multi().
  157. .PP
  158. The AES also stores the object number of the selected
  159. menu's  title in msg[3], and the object number of the
  160. selected menu item in msg[4].  Generally, your application
  161. will process menu messages with nested C switch statements.
  162. The outer switch will have one case for each menu title, and
  163. the inner switch statements will have a case for each entry
  164. within the selected menu.  (This implies that you must give a
  165. name to each title and to each menu entry when you create the
  166. menu in the RCS.)
  167. .PP
  168. After the user has made a menu selection, the AES leaves
  169. the title of the chosen menu in reverse video to indicate
  170. that your application is busy processing the message.  When
  171. you done with whatever action is indicated, you need to
  172. return the title to a normal state. This is done with
  173. .FB menu_tnormal()
  174. menu_tnormal(ad_menu, msg[3], TRUE);
  175. .FE
  176. .sp 1
  177. .ce 1
  178. (Remember that msg[3] is the title's object number.)
  179. .sp 1
  180. When your application is ready to terminate, it should
  181. delete its menu bar.  Do this with the call:
  182. menu_bar(ad_menu, FALSE);
  183. .SH GETTING FANCY
  184. The techniques above represent the bare
  185. minimum to handle menus.  In most cases, however, you will
  186. want your menus to be more "intelligent" in displaying the
  187. user's options.  For instance, you can prevent many user
  188. errors by disabling inappropriate choices, or you c